---@meta

---BufferedAction 类，表示动作对象
---@class BufferedAction
---@field doer EntityScript? 执行动作的实体（通常是玩家或生物）
---@field target EntityScript? 动作的目标实体
---@field invobject EntityScript? 使用的物品/工具（来自背包）
---@field pos Vector3? 动作的位置坐标（DynamicPosition对象）
---@field action Action? 动作类型（Action对象），即动作的定义表
---@field recipe table? 配方信息（用于制作类动作）
---@field rotation number? 旋转角度（默认为0）
---@field distance number? 动作距离
---@field arrivedist number? 到达距离
---@field forced boolean? 是否强制执行
---@field skin string? 皮肤信息
---@field options table? 额外选项表

---自定义范围检查函数类型
---@alias RangeCheckFn fun(doer: EntityScript, target: EntityScript, bufferedaction?: BufferedAction): boolean

---自定义到达检查函数类型
---@alias CustomArriveCheckFn fun(doer: EntityScript, dest: Vector3): boolean, boolean?

---主题音乐函数类型
---@alias ThemeMusicFn fun(act: BufferedAction): string?

---动作前回调函数类型
---@alias PreActionCb fun(bufferedaction: BufferedAction): nil

---显示瓦片放置器函数类型
---@alias ShowTilePlacerFn fun(action: Action): boolean

---动作执行函数类型
---@alias ActionFn fun(act: BufferedAction): boolean, string?

---组件动作类型枚举
---@alias ComponentActionType
---| "SCENE" # 适用于与世界中的对象直接交互
---| "USEITEM" # 使用背包中的物品对世界中的对象进行操作
---| "POINT" # 在世界中的特定位置使用物品
---| "EQUIPPED" # 使用已装备的物品对目标进行操作
---| "INVENTORY" # 直接使用背包中的物品，不需要目标对象
---| "ISVALID" # 验证特定动作是否对该实体有效

---SCENE 类型的组件动作函数参数
---@class SceneActionParams
---@field inst EntityScript 目标实体（被交互的对象）
---@field doer EntityScript 执行者（进行交互的角色）
---@field actions table 动作列表（用于添加可执行的动作）
---@field right boolean? 是否为右键操作

---USEITEM 类型的组件动作函数参数
---@class UseItemActionParams
---@field inst EntityScript 使用的物品
---@field doer EntityScript 执行者
---@field target EntityScript 目标对象
---@field actions table 动作列表
---@field right boolean? 是否为右键操作

---POINT 类型的组件动作函数参数
---@class PointActionParams
---@field inst EntityScript 使用的物品
---@field doer EntityScript 执行者
---@field pos Vector3 目标位置
---@field actions table 动作列表
---@field right boolean? 是否为右键操作
---@field target EntityScript? 可选的目标对象

---EQUIPPED 类型的组件动作函数参数
---@class EquippedActionParams
---@field inst EntityScript 装备的物品
---@field doer EntityScript 执行者
---@field target EntityScript 目标对象
---@field actions table 动作列表
---@field right boolean? 是否为右键操作

---INVENTORY 类型的组件动作函数参数
---@class InventoryActionParams
---@field inst EntityScript 背包中的物品
---@field doer EntityScript 执行者
---@field actions table 动作列表
---@field right boolean? 是否为右键操作

---ISVALID 类型的组件动作函数参数
---@class IsValidActionParams
---@field inst EntityScript 实体对象
---@field action Action 要验证的动作
---@field right boolean? 是否为右键操作

---组件动作函数类型
---@alias ComponentActionFn 
---| fun(params: SceneActionParams): nil
---| fun(params: UseItemActionParams): nil
---| fun(params: PointActionParams): nil
---| fun(params: EquippedActionParams): nil
---| fun(params: InventoryActionParams): nil
---| fun(params: IsValidActionParams): nil

---动作数据配置
---@class ActionData
---@field priority number? 动作优先级，数字类型，默认值0
---@field instant boolean? 决定动作是否立即执行，不需要移动或等待状态图完成，默认值false
---@field rmb boolean? 标识这个动作是否通过右键触发，默认值nil
---@field distance number? 执行该动作时玩家与目标之间的最大允许距离，默认值nil
---@field mindistance number? 最小执行距离，默认值nil
---@field arrivedist number? 到达距离，默认值nil
---@field ghost_valid boolean? 制动作是否在玩家死亡变为幽灵状态时可用，默认值false
---@field ghost_exclusive boolean? 制动作是否仅在幽灵状态下可用，活着时不可用，默认值false
---@field mount_valid boolean? 控制动作是否在玩家骑乘状态下可用，默认值false
---@field encumbered_valid boolean? 控制动作是否在玩家负重状态下可用，默认值false
---@field floating_valid boolean? 是否对漂浮状态有效，默认值false
---@field paused_valid boolean? 控制动作是否在游戏暂停状态下可用，默认值false
---@field canforce boolean? 控制动作是否可以被强制执行，默认值nil
---@field rangecheckfn RangeCheckFn? 自定义范围检查函数，默认值nil
---@field silent_fail boolean? 是否静默失败，默认值nil
---@field actionmeter boolean? 是否显示动作进度条，默认值nil
---@field invalid_hold_action boolean? 是否为无效的持续动作，默认值nil
---@field customarrivecheck CustomArriveCheckFn? 自定义到达检查函数，默认值nil
---@field is_relative_to_platform boolean? 是否相对于平台，默认值nil
---@field disable_platform_hopping boolean? 是否禁用平台跳跃，默认值nil
---@field skip_locomotor_facing boolean? 是否跳过移动朝向，默认值nil
---@field do_not_locomote boolean? 是否不移动，默认值nil
---@field extra_arrive_dist number? 为特定动作添加额外的到达距离计算，默认值nil
---@field tile_placer string? 指定要使用的瓦片放置器prefab名称，默认值nil
---@field show_tile_placer_fn ShowTilePlacerFn? 显示瓦片放置器的函数，默认值nil
---@field show_primary_input_left boolean? 在hover提示中显示主要输入按键的提示，默认值nil
---@field show_secondary_input_right boolean? 在hover提示中显示次要输入按键的提示，默认值nil
---@field theme_music string? 执行动作时播放的音乐，默认值nil
---@field theme_music_fn ThemeMusicFn? 客户端主题音乐函数，默认值nil
---@field pre_action_cb PreActionCb? 动作前回调函数，默认值nil
---@field map_action boolean? 是否为地图动作，默认值nil
---@field closes_map boolean? 是否关闭地图，默认值nil
---@field map_only boolean? 是否仅在地图上存在，默认值nil
---@field map_works_on_unexplored boolean? 是否对未探索区域生效，默认值nil

---Action 类，表示动作定义
---@class Action : ActionData
---@field id string 动作的唯一标识，字符串，一般是大写英文
---@field str string 动作的名称，字符串，自动添加到STRINGS.ACTIONS[action.id]中用于本地化

---动作失败数据配置
---@class ActionFailData
---@field [string] string 失败原因对应的提示内容

---完整的动作配置
---@class ActionConfig
---@field actiondata ActionData? Action的构造函数数据
---@field id string 动作的唯一标识，字符串，一般是大写英文
---@field str string 动作的名称，字符串，自动添加到STRINGS.ACTIONS[action.id]中用于本地化
---@field fn ActionFn 触发动作时执行的逻辑函数
---@field type ComponentActionType 组件动作类型
---@field needcomponent string 动作绑定的组件名
---@field componentactionfn ComponentActionFn 动作的采集函数，决定系统在什么情况下将动作添加到动作列表中
---@field actionstring string? 人物动作动画的名称，用于决定人物在执行该动作时播放什么动画
---@field faildata ActionFailData? 动作失败时的字符串配置

---动作配置表类型
---@alias ActionConfigList ActionConfig[] 